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Introduction 


Remember, DON'T PANIC. This is the new, improved introduc- 
tion to the Hitchhiker's Guide to the BIOS, which describes 
the BIOS (and many other aspects) of Atari's ST computer 
series. The introduction still won't tell you much, but at 
least it tells you not to panic. 

The Guide's intended audience: 

Application writers (who will find some of the func- 
tions and hints here invaluable): 

Those wishing to make use of some of the ST's 
hardware-specific features (hacking palette colors, 
configuring the RS232 port, and so on); 

Those writing device drivers , video games , or 
cartridge-based applications ; 

The habitually curious (including trivia trippers, 
information junkies, and documentation addicts). 


For many reasons this should still be considered a prelim- 
inary document. A whole host of things remain undocumented, 
many GEMDOS issues’ have not even been approached by our 
friends at Digital Research, and there are a /whole lot/ or 
festures we'd like to add to the software. 


Periodically, as our roving reporters discover new ways to 
enjoy life on a roving reporter's budget of one penebian 
slime dollar a day, we will be updating the Hitchhiker s 
Guide to reflect sudden, violent changes in reality. Those 
fortunates who do NOT own a Sub-etha Net auto-regressive 
pan-galactic update droid (if you DO own one, you know how 
difficult they are to get rid of) will have to call Atari 
occasionally to see if an update has occurred. We have no 
plans for another release before the end of September. 
Don't call /too/ often; there's an entire /galaxy/ of intel- 
ligent beings out there, and our operators are getting 
freaked out. 


REWARD ; 

One Denebian Slime Dollar to the first discoverer of a 
documentation error. /Two/ slime dollars to the second dis 
coverer , and so on .... 
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GEMDOS BIOS Calls: 
Description 
and 

Deviation from the GEMDOS Spec. 


The ST BIOS, contrary to the GEMDOS specification, is call* 
able from the 68000's user mode. 

The BIOS is re-entrant to three levels. That is, there may 
be up to three recursive BIOS calls before the system runs 
into trouble. No level checking is performed; the first 
sign of an overflow will be mysterious system behavior, and 
an eventual crash. 

Applications should NOT attempt disk or printer I/O (this 
includes getbpb calls, and standard-output redirected to the 
printer device) in critical-error, system-timer or process- 
terminate handlers . 


NOTE 

The BIOS modifies the function number (and the re- 
turn address) pushed on the stack by the applica- 
tion. The function number on the stack will be ZERO 
on return. [For* the curious: this feature saved 
several cycles per BIOS call ... 3 


( 0 ) getmpb 

VOID getmpb (p_mpb) 

LONG p_mpb; 

Upon entry, 'p_mpb' points to a ' sizeof (MPB ) ' 
block to be filled in with the system initial 
Memory Parameter Block. Upon return, the MPB is 
filled in. 

Structures are: 

#define MPB struct mpb 

tdefine MD struct md 
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♦define PD struct pd 


MPB { 

MD *mp_mfl; /* 

MD *mp_mal ; /* 

MD *mp_rover; I* 

}; 

MD { 

MD *m_link; /* 

long ra_start : 
long m_length; 

PD *m_own; 


}; 


memory free list */ 
memory allocated list */ 
roving ptr */ 


next MD (or NULL) */ 
saddr of block */ 

♦bytes in block */ 
owner's process descriptor 


[See 'System Variables' for more information 
about setting up the initial TPA.3 


( 1 ) bconstat 

WORD bconstat (dev) 

WORD dev : f - ... 

Return character -device input status, DO.L will 
be $0000 if no characters available, or $ffff if 
(at least one) character is available. 'dev' can 
be one of : 


0 PRT: (printer, the parallel port) 

1 AUX: (aux device, the RS232 port) 

2 CON: (console, the screen) 

3 MIDI port (Atari extension) 

4 Keyboard port (Atari extension) 

5 Raw console output 


Legal operations 

on 

(0) 

character 

(1) 

devices 

(2) 

are: 

(3) 

(4) 

(5) 

Operation 

PRT 

AUX 

CON 

MIDI 

KBD 

RAW 

bconstat ( ) 

no 

yes 

yes 

yes 

no 

no 

bconin( ) 

yes 

yes 

yes 

yes 

no 

no 

bconout( ) 

yes 

yes 

yes 

yes 

yes 

yes 

bcostat( ) 

yes 

yes 

yes 

yes 

yes 

no 


The MIDI device has an interrupt-driven input 
buffer of 80 characters. 


The keyboard device (^4) is output-only, and can 
be used to configure the intelligent keyboard (or 
drive it insane). 

The raw console device (#5) prints characters to 
the screen without interpretation (control 
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characters and escape sequences have no special 
meaning ) . 


(2) bconin 

WORD bconin (dev) 

WORD dev; 

'dev' is the character device number described in 
function 1; 

Does not return until a character has been input 
(busy-wait). It returns the character value in 
DO.L, with the high word zero. 

For the console (CON: , device 2) it returns the 
IBM-PC compatible scancode in the low byte of the 
upper word, and the Ascii character in the low 
byte of the low word. 

If bit 3 in the system variable 'conterm' is set, 
then the high byte of the upper word will contain 
the value of the system variable 'kbshift' for 
that keystroke. [The default state for 'con- 
term%%3' is OFF.] 

( 3 ) bconout 

WORD bconout ( dev , c ) 

WORD dev . c ; 

'dev' is the character device number described in 
function 1. 

Output character 'c' to the .device. Does not 
return until the character has been written. 

For PRT: returns 0 for failure and !0 for success. 

( 4 ) rwabs 

LONG rwabs (rwf lag, buf , count, recno, dev) 

WORD rwf lag; 

LONG buf; 

WORD count, recno, dev; 

Read or write logical sectors on a device 
'rwf lag' is one of : 

0 read 

1 write 

2 read, do not affect media-change 

3 write, do not affect media-change 


'buf' points to a buffer to read or write to 
{ unaligned transfers — on odd boundaries — are 
permitted, but they are slow). 'count' is the 
number of sectors to transfer, 'recno' is the 
logical sector number to star,t the transfer at. 
'dev' is the device number, and on the ST is one 
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of : 


0 Floppy drive A: 

1 Floppy drive B: (or '‘logical*' drive A; 
on single-disk systems). 

2+ Hard disks, networks, etc. 


On return, OL indicates a successful operation./ 
Any negative number indicates an error condition. 
(It is the responsibility of the BIOS to detect 
media changes . and return the appropriate error 
code ) . 

Modes 2 and 3 force a physical disk operation 
that will NOT affect media change, nor result in 
one (this allows the GEMDOS disk formatter, for 
instance, to read and write logical sectors after 
formatting a disk, and still allow the BIOS to 
recognize a media change on the volume just for- 
matted ) . 

[explain about "insert-disk" critical error hack 
for single-drive systems] 


( 5 ) setexc 

LONG setexc ( vecnum , vec ) 

WORD vecnum; 

■ LONG vec ; 

'vecnum' is the number of the vector to get or 
set. 'vec' is the' address to setup in the vector 
slot; no set is done if 'vec' is -IL. The 
vector's previous value is returned. 

Vectors $00 through $FF are reserved for the 
68000. 

Logical vectors $100 through $1FF are reserved 
for GEMDOS. Vectors currently implemented are: 

$100 System timer interrupt 
$101 Critical error handler 
$102 Process terminate hook 
$103.. $107: Currently unused, reserved 

Logical vectors $200 through $FFFF are reserved 
for OEM use. The ST BIOS makes no provision for 
these . 

(6) tickcal 

LONG tickcal () 

Returns a system- timer calibration value, to the 
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nearest millisecond. 

This is a silly function, since the number of 
elapsed milliseconds is passed on the stack dur- 
ing a system-timer trap. 

(7) ’^getbpb 

BPB ^getbpb(dev) 

WORD dev: 

'dev' is a device number (0 for drive A, etc. ) 
Returns a pointer to the BIOS Parameter Block for 
the specified drive, or OL if (for some reason) 
the BPB cannot be determined. 

(8) bcostat 

LONG bcostat (dev) 

'dev' is a character device number, as in func- 
tion 1. Returns character output status; 

-1 Device is ready to send (no waiting on 
next device-output call). 

0 Device is not ready to send. 

Note: Device 3 is keyboard and 4 is midi. 


(9) mediach 

LONG mediach ( dev ) 

WORD dev ; 

'dev' is a drive number. Returns one of: 

0 Media definitely has not changed 

1 Media /might/ have changed 

2 Media definitely has changed 

GEMDOS will respond to a return value of '1' with 

a read operation. If the BIOS detects an abso- 
lute media change, it will return a "media 
change" error at that time. 

(10) drvmap 
LONG drvmap ( ) 

Returns a bit-vector that contains a '1' in a bit 
position (0 .. 31) when a drive is available for 
that bit, or a 0 if there is no drive available 
for the bit. 

Installable disk drivers must correctly maintain 
the longword '_drvbits' [see: System Variables]. 

(11) kbshift 

LONG kbshift ( mode ) 

WORD mode; 

If 'mode' is non-negative, sets the keyboard 
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shift bits accordingly and returns the old shift 
bits. If 'mode' is less than zero, returns the 
IBM- PC compatible state of the shift keys on the 
keyboard, as a bit-vector in the low byte of DO. 

Bit assignments are: 

0 Right shift key 

1 Left shift key 

2 Control key 

3 ALT key 

4 Caps -lock 

5 Right mouse button (CLR/HOME) 

6 Left mouse button (INSERT) 

7 (reserved, currently zero) 
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Extended BIOS Functions 


These functions are available through trap 14. The calling 
conventions are the same as for trap 13. Contrary to the 
GEMDOS specification, the caller does NOT have to be in 
supervisor mode. It is the caller's responsibility to 
cleanup arguments passed to the trap (as per the C calling 
standard ) . 

A typical trap handler, one that works from a C binding, 
might be: 

_trapl4 : 


move . 1 

(sp)+,trl4ret 

: pop ret 

addr 

trap 

#14 

; do BIOS 

func 

move - 1 

trl4ret , - ( sp) 

; return 

to 

rts 

caller 


bss 





trl4ret: ds . 1 ; saved ret. addr 


and it might be used like: 


/•k 

* Stupid way to set the screen 

k/ 

set_screen_to ( v ) 

WORD v; 

{ 

extern long trapl4(): 
register WORD *p; 
register int i; 


to a single value. 


scrbase = (WORD *)trapl4(3); 
for (i = 0x4000; i; — i) 

*p++ = v: 


/k 

* Xor palettes in a range with a given value 

k/ 

set_palette_range( start , fin, v) 

WORD start, fin, v; 

{ 

while (start <= fin) 

trapl4(7, trapl4(7, -1) " v); 
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} 


(0 ) initmous 

VOID initmous (type, param, vec) 

WORD type; 

LONG param, vec; 

Initialize mouse packet handler, 'type' is one 
of : 


type Action 

0 disable mouse 

1 enable mouse, in relative mode 

2 enable mouse, in absolute mode 

3 ( unused ) 

4 enable mouse, in keycode mode 

'param' points t 0 ‘ a parameter block that should 
look like: 

struct param { 

BYTE topmode; 

BYTE buttons ; 

BYTE xparam; 

BYTE yparam; 

}; 


'topmode' should be: 

0 Y_position == 0 at bottom 

1 Y_position == 0 at top 

'buttons' is a parameter for the keyboard's "set 
mouse buttons " command . 

'xparam' and 'yparam' are the X and Y threshold, 
scale or delta factors, depending on the mode the 
mouse is being placed in. 
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For mouse absolute mode, some extra parameters 
immediately follow the parameter block: 

struct extra { 

WORD xmax; 

WORD ymax; 

WORD xinitial: 

WORD yinitial ; 


'xmax' and 'ymax' specify the maximum X and Y 
mouse positions. 'xinitial' and 'yinitial' 
specify the initial X and Y mouse position. 

'vec' points to a mouse interrupt handler; see 
extended function number 34, 'kbdvbase', for 
further information about ikbd subsystem 
handlers . 

(1) ssbrk 

LONG ssbrk ( amount ) 

WORD amount ; 

Reserve 'amount' bytes from the top of memory 
Returns a long pointing to the base of the allo- 
cated memory. This function MUST be called 
before the os is initialized, 

'ssbrk' is actually pretty useless. It DOES NOT 
work after GEMDOS has been brought up, since the 
TPA has already been set up. 

(2) _physBase 

LONG _physBase( ) 

Get the screen's physical base address (at the 
beginning of the next vblank ) . 

, (3) _logBase 

LONG _logBase( ) 

Get the screen's logical base, right away. This 
is the location that GSX uses when drawing to the 
screen. 

(4) _getRez 

WORD _getRez( ) 

Get the screen's current resolution (returning 0, 
1 or 2 ) . 

(5) _setScreen 

VOID _setScreen( logLoc , physLoc, rez ) 

LONG logLoc, physLoc ; 

WORD rez ; 

Set the logical screen location (logLoc), the 
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physical screen location (physLoc), and the phy- 
sical screen resolution. Negative parameters are 
ignored (making it possible, for instance, to set 
screen resolution without changing anything 
else ) . 

The logical and physical screen locations change 
immediately. 

When resolution is changed, the screen is 
cleared, the cursor is homed, and the VT52 termi- 
nal emulator state is reset. 

(6) _setPallete 

VOID _setPallete(palettePtr ) 

LONG palettePtr ; 

Set the contents of the hardware palette register 
(all 16 color entries) from the 16 words pointed 
to by 'palettePtr'. 'paletteptr' MUST be on a 
word boundary. The palette assignment takes 

place at the beginning of the next vertical blank 
interrupt. 

(7) _setColor 

WORD _setColor(colorNum. color) 

WORD colorNum, color; 

Set the palette number 'colorNum' in the hardware 
palette table to the given color . Return the old 
color in DO.W. If 'color' is negative, the 
hardware register is not changed. 

(8) _floprd 

WORD _floprd(buf, filler, devno, sectno, trackno, 
sideno, count) 

LONG buf, filler; 

WORD devno, sectno, trackno, sideno. count; 

Read one or more sectors from a floppy disk, 
'filler' is an unused longword. 'buf' must point 
to a word-aligned buffer large enough to contain 
the number of sectors requested, 'devno' is the 
floppy number (0 or 1). 'sectno' is the sector 
number to start reading from (usually 1 through 
9). 'trackno' is the track number to seek to. 
'sideno' is the side number to select. 'count' 
is the number of sectors to read (which must be 
less than or equal to the number of sectors per 
track ) . 

On return, DO contains a status code. If DO is 
zero, the operation succeeded. If DO is nonzero, 
the operation failed (and DO contains an error 
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number ) . 

(9) _flopwr 

WORD _flopwr(buf, filler, devno. sectno, trackno 
sideno , count ) 

LONG buf, filler; 

WORD devno. sectno, trackno, sideno, count; 

Write one or more sectors to a floppy disk 
'buf' must point to a word-aligned buffer, 
'filler' is an unused longword. 'devno' is the 
floppy number (0 or 1). 'sectno' is the sector 
number to start writing to (usually 1 through 9). 
'trackno' is the track number to seek to. 
'sideno' is the side number to select. 'count' 
is the number of sectors to write (which must be 
less than or equal to the number of sectors per 
track ) . 

On return. DO contains a status code. If DO is 
zero, the operation succeeded. If DO is nonzero, 
the operation failed (and DO contains an error 
number ) . 

Writing to the boot sector (sector 1, side 0, 
track 0) will cause the media to enter the "might 
have changed" state. This will be reflected on 
the next rwabs( ) or mediach( ) BIOS call. 

(10) _flopfmt 

WORD _f lopfmt ( buf , filler, devno, spt, trackno, sideno, 
interlv, magic, virgin) 

LONG buf', filler; 

WORD devno, spt, trackno, sideno, interlv, virgin; 

LONG magic; 

Format a track on a floppy disk. 'buf' must 

point to a word-aligned buffer large enough to 
hold an entire track image (8K for 9 sectors- 
per-track). 'filler' is an unused longword. 
'devno' is the floppy drive number (0 or 1). 
'spt' is the number of sectors-per-track to for- 
mat (usually 9). 'trackno' is the track number 
to format (usually 0 to 79). 'sideno' is the 
side number to format (0 or 1). 'interlv' is the 
sector-interleave factor (usually 1). 'magic' is 
a magic number that MUST be the value $87654321 . 
'virgin' is a word fill value for new sectors. 

On return. DO contains a status code. If DO is 
zero, the operation succeeded. If DO is nonzero, 
the operation failed (and DO contains an error 
number). The format function can soft-fail when 
it finds bad sectors during the verify pass. The 
caller has the choice of attempting to re-format 
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the media, or recording the bad sectors so they 
will not be included in the file system. 

A null “terminated (O.W) list of bad sector 
numbers is returned in the buffer. They are not 
necessarily in numerical order. (If there 
no bad sectors, the first word in the buffer will 
be zero.) 

A good value for 'virgin' is $E5E5. The high 
nibble of each byte in the 'virgin' parameter 
must not be equal to $F. Resist the temptation 
to format a disk with sectors initialized to 
zero . 

Formatting a track will cause the media to enter 
the "definxtely changed" state. This will be 
reflected on the next rwabs( ) or mediach( ) BIOS 
call . 

(11) used“by-BIOS 
VOID used“by“BIOS( ) 

[obsolete function] 

(12) midiws 

VOID midiws (cnt, ptr) 

WORD cnt: 

LONG ptr: . . • vu 

Writes a string to the MIDI port. cnt is^ the 
number of characters to write, minus one. ptr 
points to a vector of characters to write. 


(13) _mfpint 

VOID _mfpint( interno . vector) 

WORD interno: 

LONG vector ; . / i c ^ 

Set the MFP interrupt number 'interno (0 to loi 
to 'vector'. The old vector is written over (and 
thus unrecoverable ) . 


(14) iorec 

LONG iorec (devno) 

WORD devno : . . • / ■ 

Returns a pointer to a serial device s input 
buffer record. 'devno' is one of: 

devno Device 


0 RS232 

1 Keyboard 

2 MIDI 
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The structure of the record is: 


struct iorec 
{ 


LONG 

ibuf ; 

/* 

WORD 

ibuf siz : 

/* 

WORD 

ibufhd ; 

/* 

WORD 

ibuf tl ; 

/* 

WORD 

ibuf low: 

/* 

WORD 

ibufhi : 

/* 


}; 


pointer to buffer */ 
size of buffer */ 
head index */ 
tail index */ 
low-water mark 
high-water mark */ 


For RS-232. an output-buffer record immediately 
follows the input-buffer record. The format of 
the output-buffer record is identical. 

'ibuf' points to the device's buffer. 'ibufsiz' 
is the buffer's size. 'ibufhi' is the buffer's 
high-water mark. 'ibuf low' is the buffer's low- 
water mark. 

If flow control is enabled and the number of 
characters in the buffer reaches the high-water 
mark, the ST requests (according to the flow- 
control protocol ) the sender to stop sending 
characters. When the number of characters in the 
buffer drops below the low-water mark, the ST 
tells the sender to resume transmission. 

The flow-control operation is similar for the 
RS-232 output record. 

(15) rsconf 

LONG rsconf ( speed , flowctl. ucr . rsr, tsr . scr) 

WORD speed, flowctl, ucr, rsr, tsr. scr; 

Configure RS-232 port. If any parameter is -1 
($FFFF). the corresponding hardware register is 
not set. 'speed' sets the port's baud rate, as 
per : 

speed 


0 

1 

2 

3 

4 

5 

6 

7 

8 
9 


Rate ( bps ) 


19,200 

9600 

4800 

3600 

2400 

2000 

1800 

1200 

600 

300 
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10 

200 

11 

150 

12 

134 

13 

110 

14 

75 

15 

50 


'flow' sets the flow control, as per: 
flow Flavor 


0 No flow control [powerup default] 

1 XON/XOFF ("S/"Q) 

2 RTS/CTS 

3 XON/XOFF and RTS/CTS [is this useful?] 


'ucr', 'rsr', 'tsr', and 'scr' set the appropri- 
ate 68901 registers. 

Returns old values of ucr, rsr, tsr, and scr (that 
order) byte packed in a long value. 


(16) keytbl 

LONG keytbl (unshift, shift, capslock) 

LONG unshift, shift, capslock; 

Sets pointers to the keyboard translation tables 
for unshifted keys, shifted keys, and keys in 
caps-lock mode. Returns a pointer to the begin- 
ning of a structure: 

struct keytab { 

LONG unshift; /* -> unshift table 

LONG shift; -> shift table */ 

LONG capslock; /* -> capslock table / 

}; 


Each pointer in the structure should point to a 
table 128 bytes in length. A scancode is con- 
verted to Ascii by indexing into the table and 
taking the byte there. 

(17) ^random 

LONG _random( ) 

Returns a 24-bit psuedo-random number in DO.L. 
Bits 24.. 31 will be zero. The sequence /should/ 
be different each time the system is turned on. 
[The algorithm is from vol . 2 of Knuth' 

S = [S * C] + K 

where K = 1, C = 3141592621, and S is the seed. 
S » 8 is returned. The initial value of S is 
taken from the frame-counter '_frclock' . ] 
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The function's behavior is surprisingly good, 
except that bit 0 has an /exact/ distribution of 
50%. Therefore it is probably not a good idea to 
test individual bits and expect them to be well 
behaved . 

(18) _protobt 

VOID _protobt ( buf , serialno, disktype, execflag) 

LONG buf, serialno: 

WORD disktype, execflag: 

Prototype an image of a boot sector. Once the 
boot sector image has been constructed with this 
function, write it to the volume's boot sector. 

'buf' points to a 512-byte buffer (which may con- 
tain garbage, or already contain a boot sector 
image ) . 

'serialno' is a serial number to stamp into the 
boot sector. If 'serialno' is -1, the boot 
sector's serial number is not changed. If 'seri- 
alno' is greater than or equal to $01000000, a 
random serial number is generated and placed in 
the boot sector. 

'disktype' is either -1 (to leave the disk type 
information alone) or one of the following: 

0: 40 tracks, single sided (180K) 

1: 40 tracks, double sided (360K) 

2: 80 tracks, single sided (360K) 

3: 80 tracks, double sided (720K) 


If 'execflag' is 1, the boot sector is made exe- 
cutable. If 'execflag' is 0, the boot sector is 
made non-executable. If 'execflag' is -1, the 
boot sector remains executable or non-executable 
depending on the way it was originally. 

(19) _flopver 

WORD _f lopver ( buf , filler, devno, sectno , trackno , 
sideno, count) 

LONG buf, filler: 

WORD devno, sectno, trackno, sideno, count; 

Verify (by simply reading) one or more sectors 
from a floppy disk. 'buf' must point to a word- 
aligned 1024-byte buffer. 'filler' is an unused 
longword. 'devno' is the floppy number (0 or 1). 
'sectno' is the sector number to start reading 
from (usually 1 through 9). 'trackno' is the 
track number to seek to. 'sideno' is the side 
number to select. 'count' is the number of 
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sectors to verify (which must be less than or 
equal to the number of sectors per track). 

On return. DO contains a status code. If DO is 
zero, the operation succeeded. If DO is nonzero, 
the operation failed (and DO contains 
number ) . 


an error 


A null -terminated (O.W) list of bad sector 
numbers is returned in the buffer. They are not 
necessarily in numerical order. (If there were 
no bad sectors, the first word in the buffer will 
be zero . ) 

(20) scrdmp 

VOID scrdmp ( ) , - ■ -.u 

Dump screen to printer. [Currently this is . tne 
monochrome-only version from CES. Will be fixed 
soon . ] 

(21) cursconf 

WORD cursconf (function, operand) 

WORD function, operand; 

Configure the "glass terminal" cursor, 
'function' code is one of the following: 


The 


0 Hide cursor 

1 Show cursor 

2 Cursor set to blink 

3 Cursor set not to blink 

4 Set cursor blink timer to 'operand 

5 Return cursor blink timer value 


The cursor blink rate is based on the video scan 
rate (60hz for color. 70hz for monochrome, 50hz 
for PAL). The 'rate' parameter is equal to one- 
half the cycle time. 

(22) settime 

VOID settime (datetime) 

LONG datetime; ^ 

Sets the intelligent keyboard's idea of the time 
and date. 'datetime' is a 32-bit DOS-format 
and time (time in the low word, date in the high 
word ) . 

(23) gettime 

LONG gettime () . , ^ . 

Interrogates the intelligent keyboard s idea ot 
the time and date, and returns that value (in DOS 
format) as a 32-bit word. (Time in the low word, 
date in the high word) . 
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(24) bioskeys 
VOID bioskeys ( ) 

Restores the powerup settings of the keyboard 
translation tables. 

(25) ikbdws 

VOID ikbdws (cnt, ptr ) 

WORD cnt: 

LONG ptr; 

Writes a string to the intelligent keyboard, 
'cnt' is the number of characters to write, minus 
one. 'ptr' points to a vector of characters to 
write . 

(26) jdisint 

VOID jdisint( intno ) 

WORD intno; 

Disable interrupt number 'intno' on the 68901. 

(27) genabint 

VOID jenabint( intno ) 

WORD intno; 

Enable interrupt number 'intno' on the 68901 

(28) giaccess 

BYTE giaccess ( data , regno) 

BYTE data; 

WORD regno; 

Read or write a register on the sound chip, 
'regno' is the register number, logically ORed 
w.ith : 

$00 to read [well, oK, you don't 
/really/ OR with this...] 

$80 to write 

'data' is a byte to write to the register 

Sound chip registers are not shadowed. Pro- 
cedures that change register values by reading a 
register, modifying a local copy of it, and writ- 
ing the result back to the register, should be 
critical sections. In particular, the BIOS (fre- 
quently) updates the PORT A register, and any 
code that read-modi fy-writes PORT A must be 
atomic. [See GIACCESS at the end of this guide] 

(29) offgibit 

VOID of fgibit(bitno ) 

WORD bitno; 

Atomically set a bit in the PORT A register to 
zero . 
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(30) ongibit 

VOID ongibit ( bitno ) 

WORD bitno; 

Atomically set a bit in the PORT A register to 
one . 

(31) xbtimer 

VOID xbtimer ( timer , control, data, vec) 

WORD timer, control, data: 

LONG vec; 

'timer' is the timer number (0, 1,2, 3 

corresponding to 68901 timers A, B, C and D). 
'control' is the timer's control-register set- 
ting. 'data' is a byte shoved into the timer's 
data register. 'vec' is a pointer to an inter- 
rupt handler. 

Timers are allocated: 

Timer Usage 

A Reserved for end-users and applications 
B Reserved for graphics (hblank sync, etc.) 

C System timer (200hz) 

D RS-232 baud-rate control (this timer's 

interrupt vector is available to anyone) 


(32) dosound 

VOID dosound (ptr) 

LONG ptr; 

Set sound daemon's "program count^er to ptr 
'ptr' points to a set of commands organized as 
bytes . 

Command numbers $00 .through $0F take a one byte 
argument to be shoved into a sound chip register . 
(Command $00 shoves the byte into register 0, 
command 1 shoves the byte into register 1 , and 
you get the idea . . . ) 

Command $80 takes a one byte argument which is 
shoved into a temporary register. 

Command $81 takes three one-byte arguments. The 
first argument is a register number to load, 
using the temp register. The second argument is 
a 2's complement value to be added to the temp 
register. The third argument is the termination 
value. The instruction is executed (once on each 
update) until the temp register equals the termi- 
nation value. 

Commands $82 through $FF take a one-byte 
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argument. If the argument is zero, the sound is 
terminated. Otherwise the argument reflects the 
number of system-timer ticks (at 50hz ) until the 
next update. 

(33) setprt 

WORD setprt ( config ) 

WORD config; 

Set/get printer configuration byte. If 'config' 
is -1 ($FFFF) return the current printer confi- 
guration byte. Otherwise set the byte and return 
It's old value. 


Bits currently defined are: 


Bit# When 0 When 1 


0 

1 

2 

3 

4 

5 

6 

7 

8 

9 

10 
11 
12 

13 

14 

15 


Dot matrix 
Color device 
Atari printer 
Draft mode 
Parallel port 
Form- feed 

reserved 
reserved 
reserved 
reserved 
reserved 
reserved 
reserved 
reserved 
reserved 
Must be zero 


Daisy wheel 
Monochrome device 
” Epson" printer 
Final mode 
RS232 port 
Single sheet 


( 34 ) kbdvbase 

LONG kbdvbase ( ) 

Returns a pointer to the base of a structure: 


struct kbdvecs { 


LONG 

midivec : 

/X 

LONG 

vkbderr : 

/* 

LONG 

vmiderr ; 

/* 

LONG 

statvec ; 


LONG 

mousevec ; 


LONG 

clockvec ; 

/* 

LONG 

joyvec ; 

/* 

LONG 

midisys : 

/* 

LONG 

ikbdsys ; 

/* 


}; 


MIDI-input '^/ 
keyboard error * / 

MIDI error 
ikbd status packet 
mouse packet */ 
clock packet / 
joystick packet */ 
system MIDI vector */ 
system IKBD vector */ 


'midivec' is initialized to point to a buffering 
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routine in the BIOS. DO.B will contain a charac- 
ter read from the MIDI port. 

'vkbderr' and 'vmiderr' are called whenever an 
overrun condition is detected on the keyboard or 
MIDI 6850s. [Probably not a useful vector to 
grab . 3 

'statvec', 'mousevec', 'clockvec', and 'joyvec' 
point to ikbd status, mouse, real-time clock, and 
joystick packet handlers. The packet handlers 
are passed a pointer to the packet received in 
AO, and on the stack as a LONG. GEM/GSX uses the 
mouse vector. Handlers should return with an 
RTS, and should not spend more than 1ms handling 
the interrupt. 

The 'midisys' and 'ikbdsys' vectors are caUed 
when characters are available on the appropriate 
6850. Initially they point to default^ routines 
(the MIDI handler indirects through 'midivec', 
and the ikbd handler parses-out ikbd packets and 
calls the appropriate subsystem vectors). 

( 35 ) kbrate 

WOEUD kbrate ( initial , repeat) 

WORD initial, repeat; . . 

Get/set the keyboard's repeat rate initial 
governs the initial delay (before key-repeat 
starts). 'repeat' governs the rate at which 
key-repeats are generated. If a parameter is -1 
($FFFF) it is not changed. Times are based on 
system ticks (50hz). 

Returns the old key-repeat values, with 'initial 
in the high byte of the low word and 'repeat in 
the low byte of the low word. 

(36) _prtblk 
VOID _prtblk( ) 

Prtblk( ) primitive [see manual pages on PRTBLKJ . 

( 37 ) vsync 
VOID vsync ( ) 

Waits until the next vertical-blank interrupt and 
returns. Useful for synchronizing graphics 
operations with vblank. 

(38) supexec 

VOID supexec ( codeptr ) 

LONG codeptr; • 

'codeptr' points to a piece of code, ending in an 
RTS, that is executed in supervisor mode. The 
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code cannot perform BIOS or GEMDOS calls. This 
function is meant to allow programs to hack 
hardware and protected locations without having 
to fiddle with GEMDOS get/set supervisor mode 
call . 

( 39 ) puntaes 

VOID puntaes ( ) 

Throws away the AES, freeing up any memory it 
used. If the AES is stiH resident, it will be 
discarded and the system will reboot. If the AES 
is not resident (if it was discarded earlier) the 
function will return. 

There is NO way to throw away the AES and return 
— the reboot MUST be performed. [Ok, ok -- we 
know this is a lose.] 
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CONOUT Escape Sequences 


These are the escape functions interpreted by the BIOS ' 
conout( ) function. For the most part they emulate a VT-52 
terminal [that's the easy one to do J . There are extensions 
to hack screen colors, control screen wrap, and a few other 
simple functions. 

ESC A 
Cursor Up 

This sequence moves the cursor up one 
cursor is already on the top line of 
sequence has no effect. 

ESC B 

Cursor Down .r 

This moves the cursor down one line. If the cursor is 
already on the last line of the screen, this escape 
sequence has no effect. 


line. If the 
the screen, this 


ESC C 

Cursor Forward 

This moves the cursor one position to the right. It 
this function would move the cursor off the screen, 
this sequence has no effect. 


ESC D 

Cursor Backward ^ 

This move the cursor one position to the left. This is 
a non- destructive move because the character over 
which the cursor now rests is not replaced by a blank. 
If the cursor is already in column 0, this escape 
sequence has no effect. 


ESC E 

Clear Screen (and Home Cursor) 

This moves the cursor to column 0, row I (the top 
left-hand corner of the screen), and clears all charac- 
ters from the screen. 


ESC H 

Home Cursor 

This move the cursor to column O, row 0. The screen is 
NOT cleared. 


ESC I 

Reverse Index .... , 

Moves the cursor to the same horizontal position on the 
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preceding lines. If the cursor is on the top line, a 
scroll down is performed. 


ESC J 

Erase to End of Page 

Erases all the information from cursor (including cur- 
sor position) to the end of the page. 

ESC K 

Clear to End of Line 

This sequence clears the line from the current cursor 
position to the end of the line, 

ESC L 

Insert Line 

Inserts a new blanlc line by moving the line that cursor 
is on. end all following lines, down one line. Then, 
the curs-r is moved to the beginning of the new blank 
line . 


ESC M 

Delete Line 

Deletes the contents of the line that the cursor is on, 
places the cursor at the beginning of the line, moves 
all the following lines up one line, and adds a blank 
' line at the bottom. 

ESC Y 

Position Cursor 

The two characters that follow the "Y” specify the row 
and column to which the cursor is to be moved. The 
first character specifies the row, the second specifies 
the coium. Rows and columns number from 1 up. 


ESC b 

Set Foreground Color ' 

The Foreground Color is the color in which the charac- 
ter is displayed. 

Escape-b must be followed by a color selection charac- 
ter. Only the four least significant bits of the color 
character are used: 


Bit Pattern of Control Byte: 


7 6 5 4 3.2 1 

^ + + + + + + 

{ I I I I 

t X I X I X ! X I color index 

I I I I I 

+ + + + + 

( X = "don't care" ) 
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ESC c 

Set Background Color - 

This function selects Background Color, the color or 
the cell that contains the characters. 

Escape-c must be followed by a color selection charac- 
ter. Only the four least significant bits of the color 
character are used. (See diagram for ESC~b function) 


ESC d 

Erase Beginning of Display ^ . j- i 

This sequence erases from beginning of the display to 
the cursor position. The cursor position is erased 

also . 


ESC e 

Enable Cursor • -wi 

This sequence causes the cursor to be invisiDie. 
cursor may still be moved about on the display, 
escape sequence defined in this appendix. 


The 

using 


ESC f 

Disable Cursor ■ 

This sequence causes the cursor to be invisioie. ine 
cursor may still be moved about on the display, using 
escape sequences defined in this appendix. 


ESC j 

Save Cursor Position 

This sequence preserves the current cursor position. 
You can restore the ‘ cursor to the previously saved 
position with ESC-k. 


ESC k 

Restore Cursor Position 

This sequence restores the cursor to a previously saved 
position. If you use this sequence without having pre- 
viously saved the cursor position, then the cursor is 
moved to the home position, the top left-hand corner of 
the screen. 


ESC 1 

Erase Entire Line . , . . 

This sequence erases an entire line and moves the cur 

sor to the leftmost column. 


ESC o 

Erase Beginning of Line 

Erases from the beginning of the line to the cursor and 
includes the cursor position. 


ESC p 

Enter Reverse Video Mode 
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Enters the reverse video mode so that char^aertBIfs "-ar« 
displayed as background color characters on a fore- 
ground colored cell. 




ESC q 

Exit Reverse Video Mode 

Exits the reverse video mode. 


ESC V 

Wrap at End of Line 

This sequence causes the first character past the last 
displayable position on a line to be automatically 
placed in the first character position on the next 
line. The page scrolls up if necessary. 


ESC w 

Discard at End of Line 

Followin'^ invocation of this sequence, after the last 
displayable character on a line has been reached, the 
characters overprint. Therefore, only the last charac- 
ter received is displayed in the last column position. 
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Traps. Interrupts and Interrupt Vectors 


The ST makes use of four of the sixteen TRAP vectors pro- 
vided by the 68000- All other traps are available for 
applications. 

Trap Use 

0 ( none ) 

1 GEMDOS interface 

2 DOS extensions (GEM, GSX) 

3 ( none ) 

4 ( none ) 

5 ( none ) 

6 ( none ) 

7 ( none ) 

8 ( none ) 

9 ( none ) 

10 (none) 

1 1 ( none ) 

12 (none) 

13 BIOS 

14 Atari BIOS extensions 

15 (none) 


68901 interrupts are based at $100. The sixteen longwords 
at this location are bound by the hardware to: 

Vector Function 

$100 (disabled) Parallel port int. 

$104 (disabled) RS232 Carrier Detect 

$108 (disabled) RS232 Clear-To-Send 

$10c (disabled) 

$110 (disabled) 

$114 200hz System clock 

$118 Keyboard/MIDI [6850] 

$llc (disabled) Polled FDC/HDC 

$120 HSync (initially disabled) 

$124 RS232 transmit error 

$128 RS232 transmit buffer emtpy 

$12c RS232 receive error 

$130 RS232 receive buffer full 

$134 (disabled) 

$138 (disabled) RS232 ring indicator 

$13c (disabled) Polled monitor type 
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The divide-by-zero vector is pointed at an RTE. 

All other traps (Bus Error, et al ) are pointed at a handler 
that dumps the processor state and attempts to terminate the 
current process. [See: System Initialization] 

The Line 1010 (“Line Aye") vector is used as a short-circuit 
around the VDI to the ST's graphics primitives . It is a 
powerful and useful interface: see the 'Line A' document for 
further information. 

The Line 1111 (“Line Eff " ) trap is currently being used 
internally to the system. If you fiddle with this vector 
the AES will break. 

The FDC/HDC interrupt may be enabled by a hard disk device 
driver. The floppy disk code, however, assumes this inter- 
rupt is disabled (it busy-waits on the input bit's state). 
It is the responsibility of other drivers in the system to 
ensure that, when the floppy disk read/write/format code 
gets control, the FDC/HDC interrupt is disabled. 

The processor's normal interrupt priority level is 3. This 
is to prevent HBLANK (autovector level 2) interrupts from 
occurring on every scaniine. [it would eat about 10% ^of a 
system running in a color graphics mode, or about 22% of a 
system running in monochrome. Yuck.] The default HBLANK 
interrupt handler modifies the interrupted process IPL to 3 
and performs an RTE. This is to discourage programs from 
using IPL 0 — to use HBLANK, use an IPL of 1. 

To prevent “jittering" in programs that change screen colors 
on the fly, using the HBLANK and HSYNC interrupt vectors 
the following hack will keep the system intact and still 
yield a solid display: 

[1] Re-vector the keyboard/MIDI interrupt to a routine 
that lowers the IPL to 5 and then jumps through the 
original vector. 

[2] During the "critical" section of the screen, re- 
vector the 200hz system clock interrupt vector to 
point to a routine that increments a counter and 
RTEs . The counter keeps track of the number of sys- 
tem ticks that occur during the critical section. 

[31 After the critical section, block interrupts (at IPL 
6) and call the sytem clock handler (JMP through the 
interrupt vector, with a fake SR and return address 
on the stack) the number of times indicated by the 
counter 


(0 1985 Atari Corp. , All Rights Reserved 



TRAPS from interrupts 


November 26 , 1985 


30 


Calling the BIOS 
From an Interrupt Handler 


It is possible to do a BIOS call from an interrupt 
handler. More specifically, it is possible for EXACTLY 
ONE interrupt handler to call the BIOS at a time. It is 
NOT possible to do GEMDOS . VDI or AES traps from inter- 
rupt handlers. 

The basic problem is a critical section in the BIOS trap 
handler code. ’»'he critical section occurs when the 
registers are being saved or restored in the register 
save area: the variable ''savptr'' must be maintained 
correctly . 


* + 

* Calling the BIOS from an interrupt, safely. 

* - 

* These are from the BIOS listing: 

savptr - $4a2 ; BIOS register-save ptr 

sav_amt = 23*2 ; #words BIOS saves on the stack 

interrupt_handler : 


* Create safe TRAP environment: 
sub . 1 #sav_amt , savptr 


. lotsa BIOS traps (#13, #14 only) 


* Restore old trap environment: 
add . 1 #sav_amt , savptr 


rte 


(or whatever) 


DANGER 

Only ///ONE/// interrupt handler may do this. That is. 
two interrupt handlers cannot nest and do BIOS calls in 
this manner. 
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System Variables 


This is a list of variables in the ST BIOS that have been 
"cast in concrete" . Their locations and meanings in 
future revisions of the ST BIOS are guarenteed not to 
change . 

Any other variables in RAM. routines in the ROM, or vec- 
tors below $400 that are not documented here are almost 
certain to change. It is important not to depend on 
undocumented variables or ROM locations. 

etv^timer (long) $400 

Timer handoff vector (logical vector $100). See GEM- 
DOS documentation. 

etv_critic (long) $404 

Critical error handoff vector (logical vector $101). 
See GEMDOS documentation. 

etv_term (long) $408 

Process-terminate handoff vector (logical vector 
$102). See GEMDOS documentation. 

etv_xtra (longs) $40c 

Space for logical vectors $103 through $.107). 
memvalid (long) $420 

Contains the magic number $752019F3, which ^ (together 
with 'memval2') validates 'memcntlr' and indicates a 
successful coldstart.“ 

memcntlr (byte) $424 

Contains memory controller configuration nibble (the 
low nibble). For the full story, see. the hardware 
manual . 

resvalid (long) $426 

If 'resvalid' is the magic number $31415926 on system 
ElESET, the system will jump though 'resvector'. 

resvector (long) $42a 

System-RESET bailout vector, valid if 'resvalid' is a 
magic number. Called early-on in system initializa- 
tion (before /any/ hardware registers, including the 
memory controller configuration register, have been 
touched). A return address will be loaded into A6 . 
Both stack pointers will contain garbage. (See Rain- 
bow TOS Release Notes.) 
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phystop (long) $42e 

Physical top of RAM. Contains a pointer to the first 
unusable byte (i.e. $80000 on a 512K machine). 


_membot (long) $432 ^ 

Bottom of available memory. The getmpb 

tion uses this value as the start of the GEMDOS TPA. 


_memtop (long) $436 ^ 

Top of available memory. The getmpb Bios 
uses this value as the end of the GEMDOS TPA. 


function 


memval2 (long) $4 3a -w 

Contains the magic number $237698AA which (together 
with 'memvalid'T validates 'memcntlr and indicates a 
successful coldstart. 


flock (word) $43e 

Used to lock usage of the DMA chip. Should be 
nonzero to ensure that the OS does not touch the DMA 
chip registers during vertical blank. pevice-driver 
writers TAKE NOTE: this variable MUST be nonzero in 
order to make use of the DMA bus . 


seekrate (word) $440 u ^ 4 . 

Default floppy seek rate. Read only at boot time, 
setting this variable has no effect until you reboot. 
Bits zero and one contain the default floppy disk 
seek rate for both drives: 

00 6ms 

01 12ms 

10 2ms 

11 3ms [default] 


_timr_ms (word) $442 u w <m/i /on 
System timer calibration (in ms). Should be $14 '20 

decimal), since the timer handoff vector is called at 
50hz. Returned by BIOS function '^tickcal , and 
passed on the stack to the timer handoff vector. 


fverify (word) $444 

Floppy verify flag. When nonzero, 
floppies are read-verified. When 
verifies take place. The default 
system-reset) is to verify. 


all writes to 
zero, no write- 
state (after 


bootdev (word) $446 

** Contains the device number the system was booted 
from. The BIOS constructs an environment string from 
this variable before bringing up the desktop. 


(01985-90 Atari Corp. . All Rights Reserved 


System Variables November 26 , 1985 (Rev. 1.1 3-5-90) 33 


palmode (word) $448 

When nonzero, indicates the system is in PAL ( 50hz 
video) mode. When zero, indicates the system is in 
NTSC (60hz video) mode. 

defshiftmd (byte) $44a 

Default video resolution. If the system is forced to 
change from monochrome mode to a color resolution, 
'defshiftmd' contains the resolution the system will 
switch to. 

sshiftmd (word) $44c 

Contains shadow for 'shiftmd' hardware register: 

0 320x200x4 (low resolution) 

1 640x200x2 (medium rez ) 

2 640x400x1 (high rez / "monochrome") 


_v_bas_ad (long) $44e 

Pointer to base of screen memory. On a 512-byte 
boundary on ST and Mega, a 2-byte boundary on STE 
and an 8-byte boundary on TT. Always points to 32K 
of contiguous memory. This is "logbase." 

vblsem (word) $452 

Semaphore to enforce mutual exclusion in vertical- 
blank interrupt handler. Should be '1' to enable 
vblank processing, 

nvbls (word) $454 

Number of longwords that '_vblqueue' points to. (On 
RESET, defaults to 8 ) , 

_vblqueue (long) $456 

Pointer to a vector of pointers to vblank handlers, 
colorptr (long) $45a 

Pointer to a vector of r6 words to load into the 
hardware palette registers on the next vblank. If 
NULL, the palettes are not loaded. 'colorptr' is 
zeroed after the palettes are loaded. 

screenpt (long) $45e 

Pointer to the base of screen memory, to be setup on 
the next vblank. If NULL, the screen base is not 
changed . 

_vbclock (long) $462 

Count of vertical-blank interrupts. 
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_frclock (long) $466 

Count of vertical -blan)c interrupts that were pro- 
cessed (not blocked by 'vblsem'). 

hdv^init (long) $46a 

Vector to hard disk initialization. 

swv^vec (long) $46e 

The system follows this vector when it detects a 
transition on the "monochrome monitor detect" input 
(from low to high rez , or visa-versa). 'swv_vec' 
initially points to the system reset handler; there- 
fore the system will reset if the user changes moni- 
tors . 

hdv_bpb (long) S472 

Vector to routine to return a hard disk's Bios Param- 
eter Block (BPB). Same calling conventions as the 
BIOS function for GETBPB. 

hdv_rw (long) $476 

Vector to routine to read or write on a hard disk. 
Same calling conventions as the BIOS function for 
RWABS . 

hdv^boot (long) $47a 

Vector to routine to boot from hard disk. 
hdv_mediach (long) $47e 

Vector to routine to return a hard disk's media 
change mode. Same as BIOS binding for floppies. 

_cmdload (word) $482 

When nonzero an attempt is made to load and execute 
COMMAND. PRG from the boot device. (Load a shell or 
an application in place of the desktop). Can be set 
to nonzero by a boot sector. 

conterm (byte) $484 

Contains attribute bits for the console system: 


Bit 

0 

1 

2 

3 


Function 
nonzero : 
nonzero : 
nonzero : 
nonzero : 


zero : 


enable key-click 
enable key-repeat^ 

enable bell when *G is written to CON 
on BIOS conin( ) function, return the 
current value of 'kbshift' in bits 
24. .31 of DO.L. 
leave bits 24.. 31 alone... 
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themd (long) $48e 

mi Filled in by the BIOS on a 'getmpb' call: indicates 

^ to GEMDOS the limits of the TPA. This is used by 

GEMDOS and should not be used by other programs. 

savptr (long) $4a2 

Pointer to register save area for BIOS functions. 

_nf lops ( word ) $4a6 

Number of floppy disks actually attached to the sys- 
tem ( 0 , 1 . or 2 ) . 

sav_context (long) $4ae 

Pointer to saved processor context (more on this 
later ) . 

_bufl (long) $4b2 

Two (GEMDOS) buffer-list headers. The first list 
buffers data sectors, the second list buffers FAT and 
directory sectors. Each of these pointers points to 
a BOB (Buffer Control Block), that looks like: 




_hz_200 (long) $4ba 

” Raw 200hz system timer tick, used to divide-by-four 
for a 50hz system timer. 

the_env ( byte [ 4 ] ) $ 4be 

The default environment string. 

_drvbits ( long ) $4c4 

32-bit vector, returned by the “DRIVEMAP” BIOS func- 
tion (#10). of “live** block devices. If any floppies 
are attached, this value is at least 3. 

_dskbufp (long) $4c6 

Points to a 1024-byte disk buffer somewhere in the 
system's BSS . The buffer is ALSO used for some GSX 
graphics operations, and should not be used by inter- 
rupt routines. 


struct BCB 

BCB *b_link: next BCB */ 

int b bufdrv: /* drive#, or -1 

int bibuftyp; /* buffer type */ 

int b_bufrec; /* record# cached here / 

int b^dirty; /* dirty flag */ 

DMD *b_dm: -> Drive Media Descriptor 

char *b bufr; /* -> buffer itself */ 
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_prt cnt (word) $4ee 

Initialized to -1. Pressing the ^LT-HELP key incre- 
ments this. The screen dump code checks for $0000 to 
start imaging the screen to the printer , and checks 
for nonzero to abort the screen print. 

_sysbase (long) $4f2 

Points to the OS header block (in ROM or RAM). 


_shell_p (long) $4f6 

Points to shell-specific context. 

end os (long) $4fa i. ...u 

Points just past the last byte of low RAM used by the 
operating system. This is used as the start of the 
TPA (end_os is copied into _membot). 

exec^os (long) $4fe nTr^c 

This points to the shell that gets exec d by the BIOS 

after system initialization is complete. Normally 
this points to the first byte of the AES' text seg- 
ment . 


System Variables 


scr_dump $502 (long) 

Pointer to screen-dump code. 

prv-lsto $506 (long) * . ^ 

Pointer to code for output device status for screen- 

dump when configured for "printer" port. 

prv-lst $50a (long) . 

Pointer to code for character output for screen-dump 
when configured for "printer" port, 

prv auxo $50e ( long ) 

Pointer to code for output device status for screen- 
dump when configured for "serial" port. 

prv aux $512 (long) 

“pointer to code for character output for screen-dump 
when configured for "serial” port. 

pun ptr $516 (long) 

Pointer to a hard-disk driver data structure: see the 
hard-disk driver documentation for details. 


memval3 $51a (long) 

Still another memory-validation marker 
for cold boots . 


used to check 
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System Variables present as of Mega TOS (1.2) (continued) 


Starting at $51e, there are four sets of 8 vectors for char- 
acter device functions, as follows: 


xconstat ds.l 8 
xconin ds.l 8 
xcostat ds.l 8 
xconout ds.l 8 


$51e console status vectors 
$53e console input vectors 
$55e console output-status vectors 
$57e console output vectors 


These allow you to manipulate character based device func- 
tions at BIOS level by replacing the built-in input/output 
and status routines with your own before GEMDOS gets them. 


GEMDOS gets all its character input by trapping into the 
BIOS to a RAM based jump table. 

Each set of vectors consists of the addresses of the rou- 
tines that handle the BIOS character devices (in the fol- 
lowing order ; ) 


0 - 1st: (printer) 

1 - aux: (rs232) 

2 - con: (screen) 

*3 - midi 

^^4 - keyboard (output only) 

5 - raw console output (bypass vt52 pressure cooker) 

V'Note: for xcostat device 3 is keyboard and 4 is midi. 

No range checking is performed. If a bogus device number is 
passed to the BIOS' character I/O handler, the system will 
crash or become funky dueux. 

System Variables newer than Mega TOS (1.2) 
but useful retroactively 


_longframe $59e (word) 

When nonzero, indicates the presence of a CPU with 
long exception stack frames (i.e. not a 68000). When 
zero, indicates a 68000. Initialized to zero in old 
TOSes which are not 680x0-aware. We do ’^not’^ guaran- 
tee that newer TOSes will actually be able to accomo- 
date other CPUs . 

-.P— cookies $5a0 (long) 

Pointer to the "cookie jar" or zero (when there is no 
cookie jar). Initialized to zero (at cold boot only) 
by TOSes which do not install a cookie jar at boot 
time. See the cookie jar documentation for more 
details 
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POST MORTEM INFORMATION 

If a diagnostic cartridge is not inserted, all unused 
interrupt vectors are pointed to a handler in the BIOS 
that saves the processor's state in low memory (see 
below) and displays a number of icons in the middle of 
the screen. The handler attempts to restart the system 
after the crash — it is not always (honestly: it isn t 
very often) successful. 

The exact number of icons represents the exception that 
occurred (2 for bus error, 3 for address error, and so on 
-- see the 'Exception Processing' section in the Motorola 
68000 manual). 

The processor state is saved in an area of memory that is 
NOT touched by a system reset. Therefore it is possible 
to examine a post-mortem dump after resetting the system 
to reboot. 


* Post-mortem dump area : 

* processor state saved here on uncaught exception: 


proc_lives 

equ 

$380 

proc_dregs 

equ 

$384 

proc_aregs 

equ 

$3a4 

proc_enum 

equ 

$3c4 

proc_usp 

equ 

$3c8 

proc_st)c 

equ 

$3cc 


$12345678 iff valid 
saved D0-D7 

saved A0-A6, supervisor A7 (SSP) 
first byte is exception # 
saved user A7 

sixteen words popped from SSP 


If the longword at $380 is the magic number $12345678, 
then the following information is valid (unless it's been 
stepped on by another crash). 


D0-D7. A0-A6, and the supervisor A7 are copied to loca- 
tions $384 to $3c0. The exception number. (2 for bus 
error, etc.) is recorded in the byte at $3c4. The user 
A7 is copied to $3c8. The first sixteen words at the 
supervisor A7 are copied to the sixteen words starting at 
$3cc . 
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Getting Into and Out Of 
Supervisor Mode in GEMDOS 


DRI hasn't bothered to document this function yet. so 


Yes. there IS a way to get into (or out of) supervisor 
mode in GEIMDOS. While you read the following descrip- 
tion. please bear in mind that the original intent was to 
provide a binding usable at the C level. It is clumsy to 
use from assembly language. 

The function is Trap 1, number 32 (hex $20). It wears 
three hats; 


LONG _super( Stack ) 
LONG stack; 


If 'stack' is 1, then the function returns (in DO.L) 
either a 0 (indicating that the processor is in user mode) 
or a -1 ($FFFFFFFF indicating that the processor is in 
supervisor mode). 

If the function is called when the processor is in user 
mode. GEMDOS will return with the processor in supervisor 
mode. The old value of the supervisor stack will be 
returned in DO.L. If 'stack' was NULL ($00000000). then 
the supervisor stack will be the same as the user stack 
before the call. Otherwise the supervisor stack will be 
set to 'stack'. 

If the function is called when the processor is in super- 
visor mode, GEMDOS will return with the processor in user 
mode. 'stack' should be the value of the supervisor 
stack that was returned by the first call to the func- 
tion . 

The old value of the supervisor stack MUST restored 
before the process terminates. (Failure to do so may 
result in a crash). 
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An example of how to use it from C: 

superstuff ( ) 

{ 

long savers sp; 
long trapl ( ) ; 

/% 

* Get into supervisor mode: 

*/ 

save_ssp = trapl (0x20, OL) ; 

... do lots of supervisor stuff . . . . 

/KC 

* Get out of supervisor mode, 

* r-store old supervisor stack: 

trapl (0x20, save_ssp); 

} 
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And from assembly: 


* + 

superstuff - play around in 

Ik 

super Stuff : 


do user stuff 


clr.l “(sp) 
move.w #$20, “(sp) 
trap #1 

addq #6 , sp 

move .1 dO , savers sp 


do supervisor stuff 


move . 1 savers sp , - { sp ) 
move.w #$20, “(sp) 
trap #1 

addq #6 , sp 


do user stuff 


supervisor mode 


we want our own stack 
get/ set supervisor mode 
(do it) 

(clean up) 
save old SSP 


push old SSP 

get/ set supervisor mode 

(do it) 

(clean up) 
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GEMDOS Relocation Format 
(Clarification to GEMDOS manual) 


This is the REAL GEMDOS fixup bytestream format, as 
implemented by the function xpgmld( ) in GEMDOS (as 
opposed to what is documented in the GEMDOS manual): 


$00 no more relocation information 

$01 add $FE to the dot 

$02..$FF add N to the dot, and fixup the longword there 


So, to fixup a longword $100 bytes from the current one 
(the dot), REIiMOD would generate: 


$01 $02 


[note that only longwords can be fixed up, and that they 
must be on word boundaries.] 
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Error Handling 


Error numbers are returned by certain BIOS and most GEM- 
DOS functions. Note that some GEMDOS functions return 
WORD error numbers instead of LONG ones (that is, bits 
16.. 31 of DO.L are garbage). Someday DRI will get around 
to fixing these .... 

[Describe critical-error handler calling conventions, 
whenever DRI gets around to defining them so they're use- 
ful.] 

0 (OK) 

Successful action (the anti-error). 

-1 (ERROR) 

All-purpose error. 

-2 ( DRIVE_NOT_READY ) 

Device was not ready, or was not attached, or has 
been busy for a long time. 

-3 (UNKNOWN_CMD) 

Device didn't know about a command. 

-4 (CRC^ERROR) 

Soft error while reading a sector. 

-5 ( BAD_REQUEST ) . 

Device couldn't handle a command (the command might 
be valid in other contexts). Command parameters may 
be bad. 

-6 (SEEK_ERROR) 

Drive couldn't seek. 

“ 7 ( UNKNOWN^MEDI A ) 

Attempt to read foriegn media (usually means a cor 
rupted or zero boot sector ) . 

-8 ( SECTOR_NOT„FOUND) 

Sector could not be located. 

-9 (NO^PAPER) , 

Printer is out of paper (this cannot happen on disks, 

right? ) 
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-10 (WRITE_FAULT) 

Failure on a write operation. 

-11 (READ_FAULT) 

Failure on a read operation. 

-12 ( GENERAL^MI SHAP ) 

Reserved for future catastrophes. [This seems to be 
a useless error right now. ] 

- 1 3 ( WRI TE^PROTECT ) 

Attempt to write on write-protected or write-only 
media . 

-14 (MEDIA_CHANGE) 

Media changed since last write — the operation (read 
or write) did NOT ta)ce place. (This is more a mes- 
sage to Lhe file system than a real error). 

-15 ( UNKNOWN_DEVICE ) 

Operation specified a device the BIOS doesn't know 
anything about. 

-16 ( BAD_SECTORS ) 

Format operation succeeded (for the most part) but 
yielded bad sectors. 

-17 (INSERT_DISK) 

Ask user to insert a disk (this is more a message to 
the shell -- GEM or COMMAND. PRG -- to start a 
dialouge with the user),. 
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Cartridge Support 


There are two kinds of cartridges. 'Application' car- 
tridges are recognized by GEM and the desktop. 'Diagnos- 
tic' cartridges are executed almost immediately after 
system reset (before the 68000 touches any RAM), and may 
take over the entire system. 

The ST hardware maps cartridge space to a 128K region 
starting at $FA0000 , extending to $FBFFFF. The longword 
at $FA0000 has special meaning to the OS. It should be 
one of the following: 

$FA52255F indicates that a diagnostic cartridge 
is inserted. 

$ABCDEF42 indicates that an application cartridge 
is inserted. 

anything else is ignored. 

On system RESET, if a diagnostic cartridge is inserted 
the OS will (almost immediately) jump to location 
$FA0004. A6 will contain a return address (should the 
cartridge ever wish to continue with system initializa- 
tion). The stack pointer will be garbage. .Most of the 
.ST's hardware registers will not have been touched. The 
most significant of these registers is the memory con- 
troller -- the diagnostic cartridge is responsible for 
sizing memory and initializing the memory controller. 

Application cartridges should provide 'application 
header' at location $FA0004 (immediately following the 
magic longword) . An application header contains informa- 
tion about an application in ROM. There may be any 
number of applications in a cartridge. 


CARTRIDGE APPLICATION HEADER 


CA^NEXT 

1 

• 1 

0 

->next header 

CA_INIT 

1 

1 

4 

->init code 

CA_RUN 

I 

1 

8 

->run code 

CA^TIME 

1 

$c 

DOS time 
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t 

CAUDATE 

1 $e 

DOS date 

1 

1 

CAPSIZE 

1 $10 

1 

"size" of appl 

1 




1 

CA_NAME 

1 $14 

asciz name 


(NNNNNNNN.EEENOl 


+ + 


CA_NEXT is a pointer to the next application header. If 
CA_NEXT is $00000000, then there are no more headers in 
the list. 

CA_INIT is a nointer to the application's initialization 
code. If CA^INIT is NULL, there is no initialization 
code. The initialization vector is called at system 
startup time, as controlled by magic bits in the high 
byte of this longword (see below). 

CA_RUN is a pointer to the application's main entry 
point . 

CA_TIME and CAUDATE are DOS-format time and date stamps. 
[They are kind of useful for keeping track of version 
numbers and things like that, but are otherwise useless 
....] 

CA_SIZE is a silly field that is the "size” of the appli- 
cation. [This field is pointless, but DRI wanted it, 
sooo . . . . ] 

CA^NAME is the NULL-terminate name of the application. 
It should be in the same format as a DOS acceptable 
filename, without a path (i.e. up to eight leading char- 
acters, optionally followed by a dot and up to three 
characters of extension, and a final NUL ($00)). 

The high 8 bits (24.. 31) of CA^INIT have special meaning: 

0 “ Set to execute application (through CA_INIT vec- 

tor) before interrupt vectors, display memory 
(etc. ) have been initialized. 

1 - Set to execute application (through CA_INIT vec- 

tor) just before GEMDOS is initialized. 

2 - ( unused ) 

3 - Set to execute application (through CA_INIT vec- 

tor) immediately before a disk-boot. 

NOW*’^* Applicable to boot ROM only.] 
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4 - ( unused ) 

5 - Set if the application is a desk accessory. 

6 - Set if the application is NOT a GEM application. 

That is. it runs under DOS and doesn't do any AES 
calls. 

7 - Set if non-GEM application (see bit 6) requires 

commandline parameters before execution. 
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Vertical Blank Interrupts 


This section describes the OS's Vertical Blank Interrupt 
(VBI) handler, entered through the VBI vector at $70. 

The VBI handler increments the "frame counter" 'frclock' 
and then checks for mutual exclusion by testing 'vblsem' . 
If 'vblsem' is less than or equal to zero, no other VBI 
code is executed. Otherwise, all registers are saved on 
the stack and the "vblank counter" 'vbclock' is incre- 
mented . 

If the system is currently in high-resolution mode 
(SHIFTMD >= 2) and a low-resolution monitor is attached, 
the resolution is set to ' def shif tmd' . (or zero, if 
'defshiftmd' is >= 2). This test is necessary because 
some low-resolution monitors may "burn up" when driven by 
the ST's high-resolution video signal. 

The handler calls the cursor-blink routine. 

If 'colorptr' is nonzero, then the 16 color palettes are 
loaded from the 16 words that 'colorptr' points to. 
'colorptr' is then zeroed. 

If 'screenpt' is nonzero, then the screen's physical base 
address set to 'screenpt'. 'screenpt' is then zeroed. 

There may be any number of "deferred" VBI vectors. These 
are executed just before the VBI handler returns. The 
variable 'nvbls' contains the current number of deferred 
vector slots. 'vblqueue' points to an array of NVBL 
pointer slots that in turn point to deferred VBI code or 
NULL (in the case of an empty slot): 
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+ 4 

Ivblqueue oi + 

+ + I 



I 'NVBL' entries 

I / 

{ + + + + + + 

+->l o I I I o I I 

+ 1 + + + 1 + + 

I I 

+ > handler . . . + > handler . . . 


( 

+ 

1 

+ 


The OS initially allocates 8 VBI slots. The first slot 
is reserved for OEM's VBI code. To add another deferred 
handler, place a pointer in a free (NULL) slot. If there 
are no more free slots, then allocate a larger VBI array, 
copy the current vectors to the new array (clearing any 
new, unused entries), and update 'vblqueue' and 'nvbls'. 

Deferred VBI handlers should return with RTS, RTE. 

They may use any registers except the user stack-pointer . 

Applications are responsible for cleaning up vbl-vectors 
they have installed prior to process termination. 
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ROM System Initialization 


[1] Initial PC set from location $FC0000 , initial SP 

(trash, really) set from location $FC0004. 

Catch system RESET. Raise processor IPL to 7, exe- 
cute RESET instruction to reset hardware registers. 

If a diagnostic cartridge is inserted, load a return 
address into A 6 and jump to the cartridge. 

[2] If memory was setup (i.e. this is a warmstart ) the 
initialize the memory controller. 

[3] If the RESET-bailout vector is valid, load a return 
address into A 6 and jump to the reset handler . 

[43 Initialize the PSG (deselect floppies), setup the 

scan rate (50 or 60hz ) , write default values to the 
color palettes , "and set the display pointer to 

0 x 10000 . 

If memory was sized on a previous reset, go to step 8 

[5] Size both banks of memory. 

[ 6 ] [This used to perform a memory test. 3 

[7] Once memory has been sized and zeroed, record the 

fact by setting two magic longwords in low memory 

[83 Clear the low 64K of memory, from 'endosbss' to 
Oxffff. Initialize all kinds of 9 s variables. 
Setup interrupt vectors. Call the serial BIOS ini- 
tialization entry-point. 

[93 Execute %%2 cartridge applications. 

Initialize the screen resolution. 

[113 Execute %%0 cartridge applications. 

[123 Enable interrupts (all but HBLANK) by bringing the 
IPL to 3. 

[133 Execute %%1 cartridge applications. 
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[14] Call GEMDOS' initialization routine. 

[15] Attempt to boot from floppy disk, if the system 
variable 'bootdev' is less than 2. If there are no 
floppies, no attempt is made to boot from floppy. 

Attempt to load a boot sector from the DMA bus. For 
each of the eight DMA bus devices, a read operation 
is attempted on logical sector 0. If the read is 
successful, and the sector checksums to $1234, then 
the sector is executed. [See the section DMA Bus 
Boot" ] 

ALL devices are checked. The boot sector code may 
return, in which case the BIOS will attempt to load 
boot sectors from the rest of the devices. 

[16] Turn on the cursor. Do autoexec. Attempt to exec 
COMMAND. PEG. 

[17] Do autoexec. Kludge up an environment string. Exec 
the AES ( in ROM ) . 

If [16] or [17] ever complete, restart the system by 
going back to [1]. 
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+ 


+ 


+ 


+ 


+ 


+ 


System 

RESET 

I 

V 

+ 

Diagnostic I 

Cartridge check 1 

+ 

I 

V 


Memory Controller 1 
( fast init ) I 

+ 

I 

V 


RESET bailout I 

vector I 

+ 

I 

V 

+ 

init PSG I 

init 50hz/60hz I 

init palettes I 

display at $10000 I 
+ 


( 1 ) 


( 2 ) 


(3) 


(4) 


V 


YES 

/-< 

1 


Has memory been 
sized? [is this 
a warmstart?] 


NO I 

I 

V 

+ + 

I size memory I 

I and clear it 1 


V 

+ 

1 indicate successful I (7) 
I warmstart 1 
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V 



I Clear bottom 64K I (8) 

I Init variables I 

I Init interrupts I 

I Init serial BIOS I 




V 



I Execute %%2 cartridge I (9) 

1 applications I 



I 

V 



I Init screen I (10) 

I resolution I 



I 

V 

4 --- + 

I Execute %%0 cartridge.! (11) 

I applications I 



1 

V 



I Bring IPL to 3 ’ I (12) 

I i 



I 

V 

+ 

I Execute %%1 cartridge I (13) 

1 applications I 



I 

V 



1 Initialize GEMDOS I (14) 

I I 


V 

+ 

1 Attempt to boot 

I from floppy 




+ (15) 

l> 

l<--\ 

+ I 
i 

\-- 


\ 

I execute 
I boot 
I sector 

/ 
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I 

V 


Poll devices on 
DMA bus , requesting 
boot sectors 


•+ (15a) 
(> 


! 

V 


l<— \ 

•+ I 


execute 

boot 

sector 


\— / 


YES 

/-< 


cmdload == 0 ? 


I 

NO I 
V 


Turn on cursor 
Exec NAUTOX’^.PRG 
Exec COMMAND. PRG 


(16) 


V 


Exec \AUTO\’^.PRG 
Kludge up enviro. 
string 

Exec AES (in ROM) 


|< 

I 

V 

Reset system , 
start over again 


I (17) 

I 

I 
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PUNTAES and the 
OS Header 
(Gory Details) 


The OS variable _sysbase [$4F2] points to the base of the 
operating system. The operating system may be in ROM or 
RAM (if _sysbase is greater than phystop then the OS is 
in ROM) . 

The base of the OS is a structure that looks like: 

sysbase) \ 

/ / 


\--> I BRA to reset handler I O.w 



1 OS version number i 2.w 

H + 

I -> reset handler I 4.L 

I I 

+ + 

I -> base of OS I 8.L 

I I 

+ - + 

I -> end of OS RAM usage I $c,L 


+ + 

I (unused, reserved) I $10. L 
I I 

+ — + 

I -> GEM memory usage I $14. L 
I parameter block I 

+ + 

I Date of system build ! $18. L 
I ($YYYYMMDD) I 

+ - + 

I OS configuration bits I $lc.w 

+- + 

I DOS “format ted date the I $le.L 
I system was built I 

+ — 

I -> GEMDOS internal I $20. L 
I memory (1.2)1 

+ + 

I “> Keyboard shift I $24. L 
I state bits (1.2) I 



} -> Currently executing! $28. L 
1 GEMDOS process (1.2)1 
+ + 
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The GEM memory usage parameter block (hereinafter 
referred to as ''the magic'') informs the OS about OEM's 
memory requirements, and OEM's start address. The magic 
looks like: 


I $87654321 I O.L 

I (our favorite magic#) I 

+ — + 

I -> end of system I 4.L 

! (OS+GEM) BSS I 

^ 

I -> start (execution) 1 8.L 

i address of GEM I 

+ + 

$C 


The OS header contains a pointer to the magic. The magic 
parameter block is validated if the number $87654321 
appears in its first longword. GEIM is started up ONLY if 
there is a valid magic. In addition, on a RAM'loaded 
system, if the magic is not valid then the memory nor- 
mally used by GEM is included in the initial TPA. 

The extended BIOS call puntaes() (#39) checks to see if 
the magic is valid. If the magic is NOT valid, it 
returns ■ immediately . Otherwise it checks if the magic is 
located in ROM, and if it is, puntaes() returns. Finally 
puntaes( ) invalidates the magic (by zeroing its first 
longword) and jumps to the system reset handler. 

Puntaes will either return (meaning that the AES was 
already punted, or more accurately, that the magic was 
invalid) or clobber the magic and restart the operating 
system. The OS must be restarted because GEMDOS does not 
allow the TPA to be expanded after GEMDOS has been ini- 
tialized [ fooey ! ] . 

The country-specific configuration word ( ' ' os_conf ' ' ) 
looks something like: 

2 10 

- - — + + + + 

I I I 
I country# I PAL/ I 
I I NTSC I 
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The country-number assignments are: 


0 USA 

1 Germany 

2 France 

3 UK 

4 Spain 

6 Sweden 

7 Switzerland ( French ) 

8 Switzerland ( German ) 

9 Turkey 

Bit 0 of the word indicates NTSC when 0 and PAL when 1: 
the '' syncmode ' ^ hardware register is initialized accord- 
ingly during system startup. The country bits may be 
expanded in the future. 

The version number is $0000 for the boot ROM. and nonzero 
for ROM-based operating systems . The format of the ver- 
sion word is $WRR (W == version#. RR = release#), and 
the first OS ROMs will have the version $0100. Mega ROMS 
(blitter support) have the version number $0102. 


Several dates, in various formats, are in the header. 
The first is (more or less) human-readable, in hexade- 
cimal it is a longword that reads like $YYYYMMDD (YYYY 
year, MM = month, DD = day). The second date is a 
GEMDOS-format timestamp. 


At an offset $20 from the address at _sysbase is a pointer, 
root, which holds the base of the OS pool, 
memory used by GEMDOS . This pointer is used by FOLDERXXX . PRG 
You can still add to the pool the same way as before, but 
the OS will take the memory you added and use it differently 
than before. Exists since Mega ROMS. 

A pointer to the variable kbshift is at an offset of $24 
from _sysbase . This is a word which contains the keyboard 
shift state bits which is updated at interrupt level. Exists 
since Mega ROMS. 

The process ID (basepage address) of the process GEMDOS is 
currently executing is held by the variable _run (long) and 
is at an of set of $28 from _sysbase. Exists since Mega ROMS 

DISCLAIMER ^ • r * 

Atari makes no promises that version numbers in future 
revisions of the operating system will reflect reality, 
since the outside world's version of reality is different 
from Atari's. We may release bug fixes without changing 
the OS version number, or (contrariwise) we may change 
version numbers without changing the operating system. 
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Boot Sectors 


The boot sector contains 

o A volume serial number 
o A BIOS parameter block 
o Optional boot code and boot parameters 


An executable boot sector must word-checksum to the magic 
number $1234. During system initialization the boot sec- 
tor from a disk drive is loaded into a buffer. If the 
checksum is correct, the system JSRs the first byte of 
the buffer. [Since the location of the buffer is 
indeterminant, any code contained in the boot sector must 
be position-independent.] See the section on system ini- 
tialization for further details on writing bootable 
applications . 

When a "Get BPB" call is made, the BIOS reads the boot 
sector and examines the prototype BIOS parameter block 
(BPB). A BPB is constructed from the prototype. If the 
prototype looks strange (for instance, if critical fields 
in it are zero) the BIOS returns NULL (as an error indi- 
cation ) . 

A BPB is normally computed and written when the volume is 
formatted . 

The 24-bit serial number is used to determine if the user 
has changed disks. (see the [still nonexistent] section 
on "Disk Changes"). The serial number is computed and 
written by the FORMAT utility, and is (hopefully) unique. 


(01985 Atari Corp 


All Rights Reserved 


Boot Sectors 


November 26. 1985 


58 



BRA.S 
( wherever ) 

1 

I 

$0 

branch to boot code 


filler 

1 

1 

$2 

reserved for OEMs 


(OEM 
cruft ) 

1 

I 

1 

1 

I- 




SERIAL 

24-bit volume 
serial number 

1 

! 

1 

$8 

volume serial number 
written by FORMAT 

1 

h 

BPS 

1 

1 

$b 

#bytes/ sector 


SPC 

1 

$d 

#sectors/ cluster 

1 

h 

RES 

1 

1 

$e 

#reserved sectors 


NEATS 

1 

$10 

#FATs 

1 

h 

NDIRS 

i 

1 

$11 

tdirectory entries 

1 

h 

NSECTS 

1 

1 

$13 

#sectors on media 


MEDIA 

1 

$15 

media descriptor 

1 

h 

SPF » 

1 

1 

$16 

#sectors/FAT 

1 

h 

SPT 

1 

1 

$18 

#sectors/trac)< 

1 

h 

NSIDES 

1 

1 

$la 

#sides on media 

1 

h 

NHID 

1 

{ 

$lc 

#hidden sectors 


boot code 
(if any) 

1 

1 

$le 



$200 
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The prototype BPB is software compatible with an MS-DOS 
version 2.x BPB. (This does not mean the ST can read 
sectors written by. or write sectors readable by, a disk 
controller other than the WDC 1770/1772). 

The low byte of a 16-bit field in the BPB (such as 'BPS' ) 
occupies the lower address [as on the 8086.] 

BPS is the number of bytes per sector (for floppies on 
the ST, it will be 512). 

SPC is the number of sectors per cluster (on floppies, 
usually 2 for a cluster size of IK). 

RES is the number of reserved sectors at the beginning of 
the media, including the boot sector. RES is usually 1 
on floppies. 

NEATS is the number of File Allocation Tables on the 
media . 

NDIRS is the number of directory entries. 

NSECTS is the total number of sectors on the media 
(including the reserved sectors). 

MEDIA is a media descriptor byte. The ST BIOS does not 
use this byte, but other file-systems might. 

SPF is the number of sectors in each FAT. 

SPT is the number of sectors per track. 

NSIDES is the number of sides on the media. (Single- 

sided media can be read on double-sided drives, but not 
vice-versa ) . 

NHID is the number of "hidden" sectors. (The ST BIOS 
currently ignores this value for floppies). 

The last word in the boot sector (at offset $1FE) is 
reserved for "evening out" checksums. In particular, the 
"_protobpb" extended BIOS function modifies this word. 
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Formatting a Floppy Disk 


[1] Use the 'flopfmt()' (#10.) extended BIOS call to for- 
mat all tracks on the floppy disk. If tracks 0 or 1 
have any bad sectors then the media is unusable. 

The ST standard format is 

1 or 2 sides; 

80 tracks: 

9 sectors per track; 

no interleave (sequential sectors). 

Zero the first two tracks (this will zero the FAT and 
directory sectors). 

[2] Use the 'protobt()' (#18.) extended BIOS call to 

create a boot sector. The 'disktype' parameter 

should be 2 or 3 for 1 or 2 sided 80-track media 
respectively. The 'serialno' parameter should be a 
random number (or $1000000). 

The 'execflag' parameter should be zero unless the 
prototyping buffer contains code (such as a copy of 
the Loader) that you want executed when the disk is 
booted . 

[3] Write the boot sector, (prototyped in the buffer in 
step [2]) to track 0, side 0, sector 1 of the new 
disk. Do NOT use the 'rwabs' call; use the extended 
BIOS function 'flopwr'. 


It is possible to create disks in weird formats by vary- 
ing the number of sectors per track, formatting a few 
extra tracks, or specifying strange interleave factors. 

The 1772 "write track" codes used to format a track are: 


COUNT 

BYTE 

what 


60 

$4e 

( start 

of track) 

For each sector : 


12 

$00 



3 

$f5 

( writes 

$al ) 
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1 

1 

1 

1 

1 

1 

22 

12 

3 

1 

512 

1 

40 


$fe (ID address mark) 
track# (0..$4f) 
side# (0..1) 
sector# (1 . . 9 ) 

$02 (512 bytes/sector ) 

$f7 (2 CRCs written) 

$4e 

$00 

$f5 (writes $al ) 

$fb (data address mark) 
XX (virgin data) 

$f7 (2 CRCs written) 

$4e 


End of track: 

1401 $4e (filler at end of track) 
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DMA Bus Boot Code 


This code, extracted from the ST's BIOS, attempts to load 
boot sectors from devices on the DMA bus. The code can 
be used : 


o As an example of how to use the DMA bus (useful 
for boot-sector and device-driver writers): 


o To provide information about the timeout and 
command characteristics expected from bootable 
DMA bus devices: 


gpip 

equ 

$fffffa01 

diskctl 

equ 

$ffff8604 

f ifo 

equ 

$ffff8606 

dmahigh 

equ 

$ffff8609 

dmamid 

equ 

$ffff860b 

dmalow 

equ 

$ffff860d 

flock 

equ 

$43e 

_dskbufp 

equ 

$4c6 

_hz_200 

egu 

$4ba 


(B) 6'8^01 input register 


(W) 

(W) 

(B) 

(B) 

(B) 

(W) 

(L) 

(L) 


disk controller data access 
DMA mode control 
DMA base high 

DMA base medium . 

DMA base low 


DMA chip lock variable 
-> IK disk buffer 
200hz counter 


* dmaboot - attempt to boot from a device on the DMA bus 

* Passed: nothing 


Returns: maybe-never (although it depends ...) 


Uses: everything 

Discussion : 

Attempts to read boot sectors from eight devices connected 
to the DMA bus. If a sector is read, and it is executable 
(word checksum is $1234), then it is executed. 

This code should take about 0.5 sec to execute if nothing 
is connected to the DMA bus. Of course, if something IS 
hooked up, it should provide us with a boot sector, right? 


* _ 


dmaboot : 

moveq #0,d7 


start with dev #0 
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dmb_l : bsr 

dmaread 

y bne 

dmb_2 

ir move , 1 

dskbufp, aO 

move . w 

#$00ff ,dl 

moveq 

#0.d0 

dmb_3 : add . w 

(aO)+.dO 

dbra 

dl , dmb_3 

cmp . w 

#bootmagic .dO 

bne 

dmb_2 

move . 1 

dskbufp. aO 

jsr 

(aO) 

dmb_2 : add . b 

#$20. d7 

bne 

dmb_l 

rts 




* dmaread - attempt tc read 

* Passed: 

d7.b = dddOOO 


attempt to read boot sector 
(failed try next dev) 
aO -> disk buffer 
checksum $100 words 
checksum = 0 
add (next) word 

is the sector executable? 

( nope ) 

aO -> disk buffer 

next devno 

(do all eight devs ) 


*_ 


Returns: NE: read failed: 

EQ: successful read. 

sector data in ( ’^^dskbufp ) [ ] ; 

Preserves: d7.w 

Uses: everything else 


dmaread: 


lea 

f ifo.a6 

lea 

diskctl . a5 

St 

flock 

move . 1 

^dskbufp . - ( sp ) 

move . b 

3 ( sp ) . dmalow 

move . b 

2( sp) .dmamid 

move . b 

1 ( sp ) .dmahigh 

addq 

#4 . sp 

move . w 

#$098. (a6) 

move . w 

#$198. (a6) 

move . w 

#$098. (a6) 

move . w 

#1. (a5) 

move . w 

#$088. (a6) 

move . b 

d7.d0 

or . b 

#$08. dO 

swap 

dO 

move . w 

#$088, dO 


a6 -> DMA control register 
a5 -> DMA data register 
lock up DMA against vbiank 

setup DMA pointer 


toggle R/W. leave in Read state 


write sector count register (= 1) 

select dma bus (not SCR) 

setup dO.L with devno+command 

dO.b = devno«5 .OR. "READ” command bits 
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bsr 

bne 

wcbyte : 

dmr_q 

dO.L = xxxxxxxxDDDOlOOOxxxxxxxOlOOOlOlO 
(punt on timeout) 

dmr_lp : 

moveq 
move . 1 
bsr 
bne 
dbra 

#3,d6 

#$0000008a,d0 
wcbyte : 

dmr_q 
d6,dmr_lp 

( count = 4 ) 

dO L = generic command ($0000) 
write bytes 2, 3, 4 and 5 
(punt on timeout) 

(loop for more bytes) 


move . 1 
move . w 
bsr 
bne 

#$0000000a. (a5) 
#400, dl 
wwait 
dmr_q 

write byte 6 (final byte) 
timeout = 2.0 sec 
wait for completion 
(punt on timeout) 


move . w 
move . w 
and . w 
beq 

#$08a, (a6) 
(a5) ,d0 
#$00ff ,d0 
dmr_r 

select status reg 

get return code from DMA device 

strip crufty bits 

(return if OK) 

i( reset DMA, 

dmr_q : 

moveq 

dmr_r : move . w 

tst .b 
sf 
rts 

return NE 

#-l,d0 
#$080, (a6) 
dO 

flock 

return -1 (error) 

cleanup DMA chip for floppy driver 
(test for NE on return) 
unlock DMA chip 
return 

* + 

* wcbyte - wri 

Passed: 

a 

* 
a 

A 

te ACS I command byte, wait for IRQ 
DO.L = command. byte and FIFO control 
bits 16.. 23 = command byte, 
bits 0..7 = FIFO control bits 
a5 -> $ff8604 

* Returns : 

NE on failure (timeout) 
EQ on successful ACK 

* Uses : 

dl 


K — 

wcbyte : 

wwait ; 
ww_l : 

ww_w : 

move . 1 
moveq 
add . 1 
btst .b 
beq 
cmp. 1 
bne 
moveq 
rts 

dO, (a5) 
#10. dl 
_hz_200.dl 
#5,gpip 
ww w 

_hz_200,dl 

ww_l 

#-l,dl 

: write WDC, WDL [due to jwt] 

; wait l/20th second 
; dl = time to quit at... 

; disk done? 

; (yes , return) 

; timeout? 

; (not yet -- wait some more. . . ) 

; ensure NE ( timeout error ) return 
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^ . 4 ^ ■ 

The Loader ' 


The Loader is a generic system-loader. It lives on boot 
sectors, and is brought into RAM and executed during sys- 
tem initialization. The Loader has the capability to 
load an "image" file or a set of contiguous sectors from 
disk . 

The six reserved bytes starting at offset 2 in the boot 
sector must be: 


'Loader ' 

for some tools to be able to manipulate Loader boot sec- 
tors . 

An image file contains no header or relocation informa- 
tion. It is an exact image of the program to be exe- 

cuted. The loader is capable of loading any file from 
disk, regardless of where it appears in the directory or 
whether the file is contiguous or not. 

Loader information immediately follows the BPB in the 
boot sector: 


EXECFLG 

1 

1 

$le 

_cmdload 

LDMODE 

1 

1 

$20 

load mode 

SSECT 

1 

1 

$22 

sector start 

SECTCNT 

1 

1 

$24 

#sectors 

LDADDR 

I 

1 

1 

1 

$26 

load-address 

FATBUF 

1 

1 

$ 2 a 

FAT address 
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+ + 

I FNAME n I 

I n I 

i n I 

I n I 

I n 1 

I n I 

I n 1 

I n I 

i e I 

I e i 

I e i 

+ + 

I ( reserved ) I 

+ 

I BOOTH I 

I code I 


$2e 


$39 

$3a 


EXECFLG is a word that is copied to '_cmdload' . 

LDMODE governs the loading mode. If LDMODE is zero, a 
file is searched for and loaded. If LDMODE is nonzero, 
then 'SECTCNT' sectors, starting with logical sector 
number 'SSECT', are loaded from the disk. 

SSECT is the logical sector number to start loading from 
(valid iff LDMODE is nonzero). 

SECTCNT is the number of sectors to load (valid iff 
LDMODE is nonzero). 

LDADDR is the load-address of the file (or the sectors). 

FATBUF points to a place to put the FAT and directory 
sectors . 

FNAME is a filename to load (valid iff LDMODE is zero). 
It consists of eight character name and a three character 
extension . 

[See also: documentation on the BOOTGEN utility.] 
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Boot Sequence 


[1] The boot sector is loaded. The Loader takes con- 
trol of the system. 

[2] The boot device's directory and 2nd FAT buffer are 
read into memory, starting at _membot. The Loader 
searches for a file (usually) called TOS.IMG. If 
it is not found, it returns with an error code in 
DO. 

[3] TOS.IMG is read into memory, starting at $40000. 

[4] Control is passed to the first byte of TOS.IMG. 

TOS.IMG consists of three parts: 

[1] A relocator (RELOCRL) that moves TOS.IMG to where 
it expects to be executed in memory. RELOCRL 
takes control of the system, fades the screen, 
performs a fast block-copy, and passes control to 
the first byte in the operating system. 

[23 An image of the operating system ( 'prox 90K). 

[3] An image of the desktop and GEM ('prox IlOK) , 

System initialization proceeds as normal (except for 
clearing memory) once the OS has control. 
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Boot ROM 


The ST boot ROM (AKA "Das Boot") contains a subset of the 
BIOS. The only functions available relate to reading 
floppy disks. 

System initialization is identical to the normal OS pro- 
cedure. However, the locations and intepretations of the 
system variables may have changed. See the end of this 
section for a list of "safe" system variables. 

The normal cour-3 of events is: 

The boot ROM catches RESET and initializes the 
system. It puts up some pretty graphics. 
Kids'll love it. 

An attempt is made to boot from both floppies, 
'^bootdev' will contain the device number on a 
successful boot sector load. [Someday there may 
be a version of the boot ROM that understands 
about hard disks.] 

The boot sector is executed. [See-also: Loader] 


Das Boot's version number (the second word in the ROM. at 
$FC0002) is $0000. 

BIOS functions on trap 13: 

func Name [see: GEMDOS spec] 


0: [unused] 

1 : [ unused ] 

2: [unused] 

3 : [ unused ] 

4: rwabs (read only) 

5 : [ unused ] 

6 : [ unused ] 

7 : getbpb 


Extended functions on trap 14: 

func Name [see: Extended BIOS Functions] 
0: [unused] 
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1 : ssbrk 

2: [unused] 

3: [unused] 

4: [unused] 

5: [unused] 

6: [unused] 

7: [unused] 

8: _floprd (read sectors) 


DAS BOOT uses memory from $10000 to $20000 for screen 
buffers. Avoid loading stuff into this region (until you 
take over the system) when writing directly-bootable 
applications . 

Between the time when DAS BOOT was released and the time 
the first PAM-loaded systems were shipped (will be 
shipped?) the variables in low memory were added to and 
relocated. 

«<give list of '‘safe" variables here»> 
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GEMDOS CALL 

(QUICKER) REFERENCE GUIDE 


Functions are available through trap #1. The first 
number is the trap number (first word on the stack when 
the trap is made). The function's name (as given in 
OSBIND.H) is next, along with the named arguments. The 
number in brackets is the number of bytes that must be 
cleaned up off the stack after the call is made (for 
those of us doing traps from assembly). The argument 
declarations (if any) follow the first line. Then a 
short description of the function is given. 

In general, GEMDOS calls return LONGs in DO. However, 
there /are/ exceptions. When testing for error returns, 
it is best to examine DO.W only. In addition, GEMDOS may 
occasionally return BIOS error numbers (that is, between 
-1 and “31 ) . 


- $00 Pterm0( ) [2] r ^ 

Terminate process (with return code of $0). 

$01 Cconin( ) [2] 

Return cooked character from stdin. 

$02 Cconout(chr) [4] 
char chr ; 

Write character to stdout. 

$03 Cauxin( ) [2] 

Return character from AUX : . 

$04 Cauxout(chr) [4] 
char chr ; 

Write character to AUX:. 

$05 Cprnout(chr) [4] 
char chr ; 

Write character to PRN: . 

$06 Crawio(wrd) [4] 

WORD wrd ; 

If (wrd == OxOOff) return char from stdin 

If (wrd != OxOOff) print it on stdout; 
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$07 Crawcin( ) [2] 

Return raw character from stdin (without echo). 
$08 Cnecin( ) [2] 

Read char from stdin without echo. Control 
characters ("S, "Q, "O are interpreted and 

have effect. 

$09 Cconws(str) [6] 
char *str; 

Write null-terminated string to stdout. 

$0a Cconrs(buf) [6] 
char *buf ; 

Read edited string from stdin. On entry, 
buffo] contains size of data part of buff]. On 
exit, buffi] contains number of characters in 
data part of buff]. The data part of buff] 
starts at buff 2] 

$0b Cconis( ) (2 ] 

Return -1 (nonzero] if character is available 
on stdin, 0 otherwise. 

$0e Dsetdrv(drv) [4] 

WORD drv: 

Select current drive (0=A:, 1=B: , etc.). 

Returns a bitmap of drives in the system (bit 0 
= A ) 

$10 Cconosf) f2] 

Returns -1 [nonzero] if console is ready to 

receive a character, 0 if it is "unavailable." 

$11 Cprnos( ) (2] 

Returns -1 (nonzero] if Pl^: is ready to 

receive a character, 0 if it is "unavailable." 

$12 Cauxis( ) f 2 ] 

Returns -1 [nonzero] if char is available on 
AUX : , 0 otherwise. 

$13 Cauxos( ) [2] 

Returns -1 [nonzero] if AUX: is ready to 

receive a character, 0 if it is "unavailable." 

$19 Dgetdrv( ) [2] 

Returns number of current drive (0=A:, etc.) 

$la Fsetdta(ptr) [6] 

LONG ptr : . , ^ X 

Set disk transfer address (used by Fsfirst()). 
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$20 Super (stack) [6] 

LONG stack; , . • 

Hack processor privilege mode. If 'stack is 
IL, return 0 or -1 (processor is in user or 
supervisor mode). If in user mode, switch to 
supervisor mode and use 'stack' as the supervi- 
sor stack (of the value from USP if 'stack' is 
NULL). If in supervisor mode, switch to user 
mode and use 'stack' as the supervisor stack. 
Return the old supervisor stack value, 

$2a Tgetdate() [2] 

Returns date: 


bits 
0. .4 

day 1 . . 

31 

5. .8 

month 1 

. .12 

9. .15 

year 0 . 

.119 since 1980 


$2b Tsetdate(date) [4,] 

WORD date; 

Set date in the format described above. 

$2c Tgettime( ) [2] 

Return time in the format; 

bits 

0..4 second 0..59 (2-second resolution) 

5 . . 10 minute 0 . . 59 

11. . 15 hour 0. .23 


$2d Tsettime( time ) [4] 

WORD time; 

Set time in the format described above. 

$2f Fgetdta() [2] 

Return current DTA, 

$30 Sversion( ) [2] 

Return current version number . 

$31 Ptermres(keep, ret) [8] 

LONG keep; 

WORD ret; 

Terminate and stay resident. 'keep' has number 
of bytes to keep in the process descriptor, 
'ret' is the process' return code. 

$36 Dfree(buf, drv) [] 

LONG buf; 

WORD drv; 
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Return information about allocation on drive 
'drv' concurrent, 1=A: , 2^6:, etc.). 'buf' 

points to a structure where stuff will be 
returned: 


LONG b_free; 
LONG b_total ; 
LONG b_secsiz 
LONG b_c 1 s i z ; 


#free clusters on drive 
total tclusters on drive 
tbytes in a sector 
tsectors in a cluster 


$39 Dcreate(path) [6] 
char *path ; 

Create a directory. 

$3a Ddelete(path) [6] 
char *path; 

Delete a directory. 

$3b Dsetpath(path) [6] 
char *path; 

Set current directory. 

$3c FcreateC name , attr) [83 
char ’^name ; 

WORD attr; 

Create a file with the given pathname. Returns 
a handle or a (negative) error#. Bits in the 
attribute word are: 


$01 set to readonly 

$02 hidden from directory search 

$04 system file, hidden from dir search 

$08 volume label (first 11 bytes of name) 


$3d Fopen(name, mode) [8] 
char *name ; ; 

WORD mode ; 

Open a file. Mode is 0, 1 or 2 for read, 

write, and read/write. Returns a handle or a 
(negative) error#. 

$3e Fclose( handle ) [4] 

WORD handle; 

Close the handle. 

$3f Fread( handle , count, buf ) [12] 

WORD handle; 

LONG count: 
char *buf ; 

Read bytes from a file. Return count read, or 
a negative error#. 
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$40 Fwrite( handle, count, buf ) [12] 

WORD handle; 

LONG count; 
char *buf ; 

Write bytes to a file. Return count written, 
or a negative error#. 


$41 Fdelete(name) [6] 
char ^name; 

Delete the file. 


$42 Fseek(of f set , handle, mode) [10] 

LONG offset; 

WORD handle; 

WORD mode; , . 

Seek within the file (handle). 'offset is the 
(signed) number of bytes to seek by. Mode is 
one of : 


0 from beginning of file 

1 from current position 

2 from end of file 


$43 Fattrib(path, mode, mode) [10] 

Get file attributes if 'mode' is 0, set them if 
'mode' is 1. Bits are: 

$01 readonly 

$02 hidden 

$04 system (hidden hidden) 

$08 volume label 

$10 subdirectory 

$20 written to and closed 


$45 Fdup( stdhandle ) [4] 

WORD stdhandle ; 

Returns non-standard handle that refers to the 
same file. 

$46 Ff or ce( stdhandle, nonstdhandle ) [6] 

WORD stdhandle; 

WORD nonstdhandle; 

Force standard handle to point to same file or 
dev as the nonstandard handle. 

$47 Dgetpath( pathbuf , drv) [8] 
char ’^pathbuf ; 

WORD drv; 

Return current directory for drive 'drv 
(0=default, 1=A: , etc.) in the buffer. Buffer 
must be at least 64 bytes long. 
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$48 Malloc( amount ) [6] 

LONG amount; 

'amount' contains # bytes to allocate (or -1, 
which returns maximum available memory). 

Return pointer to block (on word boundary) of 
'amount' bytes, or zero on allocation failure. 

$49 Mfree(addr) [6] 
char *addr; 

Free a block of memory. Nonzero return on 

failure . 

$4a Mshrink( zero , mem, size) [12] 

WORD zero; 

LONG mem; 

LONG size; 

'zero' must be a word containing 0. 'mem' con- 
tains beginning of memory block. ^ 'size' is the 
the amount of memory to RETAIN in the block. 
Nonzero return on failure. 

$4b Pexec(mode, path, commandline, environment) [16] 

WORD mode; 
char *path; 
char ’^commandline ; 
char ’^environment; 

'mode' is one of: 

0 load and go 

3 just load 

4 just go 

5 create basepage 

'commandline' is the command tail, which is 
copied into the basepage. 'environment' is the 
environment string; if NULL, the parent process' 
environment string is inherited. 

For mode 0, the return code is the child's 
return code, or a negative (OS) error. If the 
load or create-basepage fails, a negative error 
number is returned. 


$4c Pterm(code) [4] 

WORD code; 

Terminate current process, returning 'code' to 
the parent. 

$4e Fsf irst( spec . attr ) [8] 
char ’^'spec; 

WORD attr; 

'attr' is a set of attributes to match (see 
function #43 for details). 'spec' may contain 


(01985 Atari Corp. , All Rights Reserved 


GEMDOS Quickref 


November 26, 1985 


76 


wildcard characters in the filename, but not in 
the pathname. Returns 0 if a file is found, 
EFILNF if no file was found. Dumps stuff into 
the DTA: 

bytes 

0 . . 20 junk 

21 file attributes 

22-23 file time stamp 

24-25 file date stamp 

26-29 file size (longword) 

30-43 name+extension of found file 


$4f FsnextO [2] 

Continue with with Fsfirst( ) . 

$56 Frename( zero . old, new) [12] 

WORD zero: 
char *old; 

char *new; ^ ^ ^ , 

Change the name of a file from 'o^d' to new , 
'zero' is reserved, and must be 0. 

$57 Fdatime ( handle , buf , set) [10] 

WORD handle: 
char ’^buf : 

WORD set * 

'buf' points to buffer containing file date and 
time information. 'handle' is a, handle to the 
file. If 'set' is zero, get the time and date. 
If 'set' is 1, set the file time and date. 
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